<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"><head>

	
		<meta http-equiv="Content-type" content="text/html; charset=UTF-8">
		<meta http-equiv="Content-Language" content="en-us">

		<title>Django | Form fields | Django Documentation</title>

		<meta name="ROBOTS" content="ALL">
		<meta http-equiv="imagetoolbar" content="no">
		<meta name="MSSmartTagsPreventParsing" content="true">
		<meta name="Copyright" content="This site's design and contents Copyright (c) 2005  Lawrence Journal-World.">

		<meta name="keywords" content="Python, Django, framework, open-source">
		<meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.">

		<link href="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/base.css" rel="stylesheet" type="text/css" media="screen">
		<link href="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/print.css" rel="stylesheet" type="text/css" media="print">
      
  
  <style type="text/css" media="screen">
    #docs-search {
      color: #000;
      float: right;
    }
    #docs-search form {
      font-size: 92%;
      margin: 0;
      padding: 1em 1em 0;
      white-space: nowrap;
    }
    form.search ul {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    form.search li {
      display: inline;
      padding-right: 1em;
    }
    form.search .query {
      width: 18em;
    }
  </style>
  <link rel="stylesheet" href="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/pygments.css" type="text/css">

	</head><body id="documentation" class="default">

	<div id="container">
		<div id="header">
			<h1 id="logo"><a href="http://www.djangoproject.com/"><img src="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/hdr_logo.gif" alt="Django"></a></h1>
			<ul id="nav-global">
				<li id="nav-homepage"><a href="http://www.djangoproject.com/">Home</a></li>
				<li id="nav-download"><a href="http://www.djangoproject.com/download/">Download</a></li>
				<li id="nav-documentation"><a href="http://docs.djangoproject.com/">Documentation</a></li>
				<li id="nav-weblog"><a href="http://www.djangoproject.com/weblog/">Weblog</a></li>
				<li id="nav-community"><a href="http://www.djangoproject.com/community/">Community</a></li>
				<li id="nav-code"><a href="http://code.djangoproject.com/">Code</a></li>
			</ul>
		</div>
		<!-- END Header -->
		<div id="billboard">
  <h2><a href="http://docs.djangoproject.com/en/1.0/">Django documentation</a></h2>
</div>
		<div id="columnwrap">
			
		<div id="content-main">
		


  <h2 class="deck">
  
    This document describes Django version 1.0. For development documentation, 
    <a href="http://docs.djangoproject.com/en/dev/ref/forms/fields/">go here</a>.
  
  </h2>
  <div class="section" id="s-module-django.forms.fields">
<span id="s-ref-forms-fields"></span><span id="module-django.forms.fields"></span><span id="ref-forms-fields"></span><h1>Form fields<a class="headerlink" href="#module-django.forms.fields" title="Permalink to this headline">¶</a></h1>
<dl class="class">
<dt id="django.forms.Field">
<!--[django.forms.Field]-->class <tt class="descname">Field</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.Field" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>When you create a <tt class="docutils literal"><span class="pre">Form</span></tt> class, the most important part is defining the
fields of the form. Each field has custom validation logic, along with a few
other hooks.</p>
<dl class="method">
<dt id="django.forms.Field.clean">
<!--[django.forms.Field.clean]--><tt class="descclassname">Field.</tt><tt class="descname">clean</tt>(<em>value</em>)<a class="headerlink" href="#django.forms.Field.clean" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Although the primary way you’ll use <tt class="docutils literal"><span class="pre">Field</span></tt> classes is in <tt class="docutils literal"><span class="pre">Form</span></tt> classes,
you can also instantiate them and use them directly to get a better idea of
how they work. Each <tt class="docutils literal"><span class="pre">Field</span></tt> instance has a <tt class="docutils literal"><span class="pre">clean()</span></tt> method, which takes
a single argument and either raises a <tt class="docutils literal"><span class="pre">django.forms.ValidationError</span></tt>
exception or returns the clean value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">EmailField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">'foo@example.com'</span><span class="p">)</span>
<span class="go">u'foo@example.com'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">u'foo@example.com'</span><span class="p">)</span>
<span class="go">u'foo@example.com'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">'invalid e-mail address'</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">ValidationError: [u'Enter a valid e-mail address.']</span>
</pre></div>
</div>
<div class="section" id="s-core-field-arguments">
<span id="core-field-arguments"></span><h2>Core field arguments<a class="headerlink" href="#core-field-arguments" title="Permalink to this headline">¶</a></h2>
<p>Each <tt class="docutils literal"><span class="pre">Field</span></tt> class constructor takes at least these arguments. Some
<tt class="docutils literal"><span class="pre">Field</span></tt> classes take additional, field-specific arguments, but the following
should <em>always</em> be accepted:</p>
<div class="section" id="s-required">
<span id="required"></span><h3><tt class="docutils literal"><span class="pre">required</span></tt><a class="headerlink" href="#required" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Field.required">
<!--[django.forms.Field.required]--><tt class="descclassname">Field.</tt><tt class="descname">required</tt><a class="headerlink" href="#django.forms.Field.required" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>By default, each <tt class="docutils literal"><span class="pre">Field</span></tt> class assumes the value is required, so if you pass
an empty value -- either <tt class="xref docutils literal"><span class="pre">None</span></tt> or the empty string (<tt class="docutils literal"><span class="pre">""</span></tt>) -- then
<tt class="docutils literal"><span class="pre">clean()</span></tt> will raise a <tt class="docutils literal"><span class="pre">ValidationError</span></tt> exception:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="go">u'foo'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">''</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">ValidationError: [u'This field is required.']</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">ValidationError: [u'This field is required.']</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">' '</span><span class="p">)</span>
<span class="go">u' '</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="mf">0</span><span class="p">)</span>
<span class="go">u'0'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">True</span><span class="p">)</span>
<span class="go">u'True'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">False</span><span class="p">)</span>
<span class="go">u'False'</span>
</pre></div>
</div>
<p>To specify that a field is <em>not</em> required, pass <tt class="docutils literal"><span class="pre">required=False</span></tt> to the
<tt class="docutils literal"><span class="pre">Field</span></tt> constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="go">u'foo'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">''</span><span class="p">)</span>
<span class="go">u''</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span>
<span class="go">u''</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="mf">0</span><span class="p">)</span>
<span class="go">u'0'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">True</span><span class="p">)</span>
<span class="go">u'True'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="bp">False</span><span class="p">)</span>
<span class="go">u'False'</span>
</pre></div>
</div>
<p>If a <tt class="docutils literal"><span class="pre">Field</span></tt> has <tt class="docutils literal"><span class="pre">required=False</span></tt> and you pass <tt class="docutils literal"><span class="pre">clean()</span></tt> an empty value,
then <tt class="docutils literal"><span class="pre">clean()</span></tt> will return a <em>normalized</em> empty value rather than raising
<tt class="docutils literal"><span class="pre">ValidationError</span></tt>. For <tt class="docutils literal"><span class="pre">CharField</span></tt>, this will be a Unicode empty string.
For other <tt class="docutils literal"><span class="pre">Field</span></tt> classes, it might be <tt class="xref docutils literal"><span class="pre">None</span></tt>. (This varies from field to
field.)</p>
</div>
<div class="section" id="s-label">
<span id="label"></span><h3><tt class="docutils literal"><span class="pre">label</span></tt><a class="headerlink" href="#label" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Field.label">
<!--[django.forms.Field.label]--><tt class="descclassname">Field.</tt><tt class="descname">label</tt><a class="headerlink" href="#django.forms.Field.label" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <tt class="docutils literal"><span class="pre">label</span></tt> argument lets you specify the "human-friendly" label for this
field. This is used when the <tt class="docutils literal"><span class="pre">Field</span></tt> is displayed in a <tt class="docutils literal"><span class="pre">Form</span></tt>.</p>
<p>As explained in "Outputting forms as HTML" above, the default label for a
<tt class="docutils literal"><span class="pre">Field</span></tt> is generated from the field name by converting all underscores to
spaces and upper-casing the first letter. Specify <tt class="docutils literal"><span class="pre">label</span></tt> if that default
behavior doesn't result in an adequate label.</p>
<p>Here's a full example <tt class="docutils literal"><span class="pre">Form</span></tt> that implements <tt class="docutils literal"><span class="pre">label</span></tt> for two of its fields.
We've specified <tt class="docutils literal"><span class="pre">auto_id=False</span></tt> to simplify the output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">label</span><span class="o">=</span><span class="s">'Your name'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">(</span><span class="n">label</span><span class="o">=</span><span class="s">'Your Web site'</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Your name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Your Web site:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-initial">
<span id="initial"></span><h3><tt class="docutils literal"><span class="pre">initial</span></tt><a class="headerlink" href="#initial" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Field.initial">
<!--[django.forms.Field.initial]--><tt class="descclassname">Field.</tt><tt class="descname">initial</tt><a class="headerlink" href="#django.forms.Field.initial" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <tt class="docutils literal"><span class="pre">initial</span></tt> argument lets you specify the initial value to use when
rendering this <tt class="docutils literal"><span class="pre">Field</span></tt> in an unbound <tt class="docutils literal"><span class="pre">Form</span></tt>.</p>
<p>To specify dynamic initial data, see the <a title="django.forms.Form.initial" class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/forms/api/#django.forms.Form.initial"><tt class="xref docutils literal"><span class="pre">Form.initial</span></tt></a> parameter.</p>
<p>The use-case for this is when you want to display an "empty" form in which a
field is initialized to a particular value. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="s">'Your name'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="s">'http://'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" value="Your name" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url" value="http://" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>You may be thinking, why not just pass a dictionary of the initial values as
data when displaying the form? Well, if you do that, you'll trigger validation,
and the HTML output will include any validation errors:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">default_data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'name'</span><span class="p">:</span> <span class="s">'Your name'</span><span class="p">,</span> <span class="s">'url'</span><span class="p">:</span> <span class="s">'http://'</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">default_data</span><span class="p">,</span> <span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" value="Your name" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;ul class="errorlist"&gt;&lt;li&gt;Enter a valid URL.&lt;/li&gt;&lt;/ul&gt;&lt;input type="text" name="url" value="http://" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;ul class="errorlist"&gt;&lt;li&gt;This field is required.&lt;/li&gt;&lt;/ul&gt;&lt;input type="text" name="comment" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>This is why <tt class="docutils literal"><span class="pre">initial</span></tt> values are only displayed for unbound forms. For bound
forms, the HTML output will use the bound data.</p>
<p>Also note that <tt class="docutils literal"><span class="pre">initial</span></tt> values are <em>not</em> used as "fallback" data in
validation if a particular field's value is not given. <tt class="docutils literal"><span class="pre">initial</span></tt> values are
<em>only</em> intended for initial form display:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="s">'Your name'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="s">'http://'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'name'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> <span class="s">'url'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> <span class="s">'comment'</span><span class="p">:</span> <span class="s">'Foo'</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
<span class="go"># The form does *not* fall back to using the initial values.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{'url': [u'This field is required.'], 'name': [u'This field is required.']}</span>
</pre></div>
</div>
<p>Instead of a constant, you can also pass any callable:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">import</span> <span class="nn">datetime</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">DateForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">day</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DateField</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">DateForm</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Day:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="day" value="12/23/2008" /&gt;&lt;td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>The callable will be evaluated only when the unbound form is displayed, not when it is defined.</p>
</div>
<div class="section" id="s-widget">
<span id="widget"></span><h3><tt class="docutils literal"><span class="pre">widget</span></tt><a class="headerlink" href="#widget" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Field.widget">
<!--[django.forms.Field.widget]--><tt class="descclassname">Field.</tt><tt class="descname">widget</tt><a class="headerlink" href="#django.forms.Field.widget" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <tt class="docutils literal"><span class="pre">widget</span></tt> argument lets you specify a <tt class="docutils literal"><span class="pre">Widget</span></tt> class to use when
rendering this <tt class="docutils literal"><span class="pre">Field</span></tt>. See <a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/forms/widgets/#ref-forms-widgets"><em>Widgets</em></a> for more information.</p>
</div>
<div class="section" id="s-help-text">
<span id="help-text"></span><h3><tt class="docutils literal"><span class="pre">help_text</span></tt><a class="headerlink" href="#help-text" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Field.help_text">
<!--[django.forms.Field.help_text]--><tt class="descclassname">Field.</tt><tt class="descname">help_text</tt><a class="headerlink" href="#django.forms.Field.help_text" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <tt class="docutils literal"><span class="pre">help_text</span></tt> argument lets you specify descriptive text for this
<tt class="docutils literal"><span class="pre">Field</span></tt>. If you provide <tt class="docutils literal"><span class="pre">help_text</span></tt>, it will be displayed next to the
<tt class="docutils literal"><span class="pre">Field</span></tt> when the <tt class="docutils literal"><span class="pre">Field</span></tt> is rendered by one of the convenience <tt class="docutils literal"><span class="pre">Form</span></tt>
methods (e.g., <tt class="docutils literal"><span class="pre">as_ul()</span></tt>).</p>
<p>Here's a full example <tt class="docutils literal"><span class="pre">Form</span></tt> that implements <tt class="docutils literal"><span class="pre">help_text</span></tt> for two of its
fields. We've specified <tt class="docutils literal"><span class="pre">auto_id=False</span></tt> to simplify the output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">HelpTextContactForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">subject</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mf">100</span><span class="p">,</span> <span class="n">help_text</span><span class="o">=</span><span class="s">'100 characters max.'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">message</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">sender</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">EmailField</span><span class="p">(</span><span class="n">help_text</span><span class="o">=</span><span class="s">'A valid e-mail address, please.'</span><span class="p">)</span>
<span class="gp">... </span>    <span class="n">cc_myself</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">BooleanField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">HelpTextContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Subject:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="subject" maxlength="100" /&gt;&lt;br /&gt;100 characters max.&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Message:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="message" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Sender:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="sender" /&gt;&lt;br /&gt;A valid e-mail address, please.&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Cc myself:&lt;/th&gt;&lt;td&gt;&lt;input type="checkbox" name="cc_myself" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">()</span>
<span class="go">&lt;li&gt;Subject: &lt;input type="text" name="subject" maxlength="100" /&gt; 100 characters max.&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Message: &lt;input type="text" name="message" /&gt;&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Sender: &lt;input type="text" name="sender" /&gt; A valid e-mail address, please.&lt;/li&gt;</span>
<span class="go">&lt;li&gt;Cc myself: &lt;input type="checkbox" name="cc_myself" /&gt;&lt;/li&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">()</span>
<span class="go">&lt;p&gt;Subject: &lt;input type="text" name="subject" maxlength="100" /&gt; 100 characters max.&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Message: &lt;input type="text" name="message" /&gt;&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Sender: &lt;input type="text" name="sender" /&gt; A valid e-mail address, please.&lt;/p&gt;</span>
<span class="go">&lt;p&gt;Cc myself: &lt;input type="checkbox" name="cc_myself" /&gt;&lt;/p&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-error-messages">
<span id="error-messages"></span><h3><tt class="docutils literal"><span class="pre">error_messages</span></tt><a class="headerlink" href="#error-messages" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<dl class="attribute">
<dt id="django.forms.Field.error_messages">
<!--[django.forms.Field.error_messages]--><tt class="descclassname">Field.</tt><tt class="descname">error_messages</tt><a class="headerlink" href="#django.forms.Field.error_messages" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <tt class="docutils literal"><span class="pre">error_messages</span></tt> argument lets you override the default messages that the
field will raise. Pass in a dictionary with keys matching the error messages you
want to override. For example, here is the default error message:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">generic</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">generic</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">''</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="nc">ValidationError</span>: <span class="n-Identifier">[u'This field is required.']</span>
</pre></div>
</div>
<p>And here is a custom error message:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">error_messages</span><span class="o">=</span><span class="p">{</span><span class="s">'required'</span><span class="p">:</span> <span class="s">'Please enter your name'</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">name</span><span class="o">.</span><span class="n">clean</span><span class="p">(</span><span class="s">''</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="nc">ValidationError</span>: <span class="n-Identifier">[u'Please enter your name']</span>
</pre></div>
</div>
<p>In the <a class="reference internal" href="#built-in-field-classes">built-in Field classes</a> section below, each <tt class="docutils literal"><span class="pre">Field</span></tt> defines the
error message keys it uses.</p>
</div>
</div>
<div class="section" id="s-built-in-field-classes">
<span id="built-in-field-classes"></span><h2>Built-in <tt class="docutils literal"><span class="pre">Field</span></tt> classes<a class="headerlink" href="#built-in-field-classes" title="Permalink to this headline">¶</a></h2>
<p>Naturally, the <tt class="docutils literal"><span class="pre">forms</span></tt> library comes with a set of <tt class="docutils literal"><span class="pre">Field</span></tt> classes that
represent common validation needs. This section documents each built-in field.</p>
<p>For each field, we describe the default widget used if you don't specify
<tt class="docutils literal"><span class="pre">widget</span></tt>. We also specify the value returned when you provide an empty value
(see the section on <tt class="docutils literal"><span class="pre">required</span></tt> above to understand what that means).</p>
<div class="section" id="s-booleanfield">
<span id="booleanfield"></span><h3><tt class="docutils literal"><span class="pre">BooleanField</span></tt><a class="headerlink" href="#booleanfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.BooleanField">
<!--[django.forms.BooleanField]-->class <tt class="descname">BooleanField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.BooleanField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">CheckboxInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">False</span></tt></li>
<li>Normalizes to: A Python <tt class="xref docutils literal"><span class="pre">True</span></tt> or <tt class="xref docutils literal"><span class="pre">False</span></tt> value.</li>
<li>Validates that the check box is checked (i.e. the value is <tt class="xref docutils literal"><span class="pre">True</span></tt>) if
the field has <tt class="docutils literal"><span class="pre">required=True</span></tt>.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt></li>
</ul>
</dd></dl>

<div class="versionchanged">
<span class="title">Changed in Django 1.0:</span> The empty value for a <tt class="docutils literal"><span class="pre">CheckboxInput</span></tt> (and hence the standard
<tt class="docutils literal"><span class="pre">BooleanField</span></tt>) has changed to return <tt class="xref docutils literal"><span class="pre">False</span></tt> instead of <tt class="xref docutils literal"><span class="pre">None</span></tt> in
the Django 1.0.</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since all <tt class="docutils literal"><span class="pre">Field</span></tt> subclasses have <tt class="docutils literal"><span class="pre">required=True</span></tt> by default, the
validation condition here is important. If you want to include a checkbox
in your form that can be either checked or unchecked, you must remember to
pass in <tt class="docutils literal"><span class="pre">required=False</span></tt> when creating the <tt class="docutils literal"><span class="pre">BooleanField</span></tt>.</p>
</div>
</div>
<div class="section" id="s-charfield">
<span id="charfield"></span><h3><tt class="docutils literal"><span class="pre">CharField</span></tt><a class="headerlink" href="#charfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.CharField">
<!--[django.forms.CharField]-->class <tt class="descname">CharField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.CharField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates <tt class="docutils literal"><span class="pre">max_length</span></tt> or <tt class="docutils literal"><span class="pre">min_length</span></tt>, if they are provided.
Otherwise, all inputs are valid.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">max_length</span></tt>, <tt class="docutils literal"><span class="pre">min_length</span></tt></li>
</ul>
</dd></dl>

<p>Has two optional arguments for validation:</p>
<dl class="attribute">
<dt id="django.forms.CharField.max_length">
<!--[django.forms.CharField.max_length]--><tt class="descclassname">CharField.</tt><tt class="descname">max_length</tt><a class="headerlink" href="#django.forms.CharField.max_length" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.forms.CharField.min_length">
<!--[django.forms.CharField.min_length]--><tt class="descclassname">CharField.</tt><tt class="descname">min_length</tt><a class="headerlink" href="#django.forms.CharField.min_length" title="Permalink to this definition">¶</a></dt>
<dd>If provided, these arguments ensure that the string is at most or at least
the given length.</dd></dl>

</div>
<div class="section" id="s-choicefield">
<span id="choicefield"></span><h3><tt class="docutils literal"><span class="pre">ChoiceField</span></tt><a class="headerlink" href="#choicefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.ChoiceField">
<!--[django.forms.ChoiceField]-->class <tt class="descname">ChoiceField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.ChoiceField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">Select</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates that the given value exists in the list of choices.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid_choice</span></tt></li>
</ul>
</dd></dl>

<p>Takes one extra required argument:</p>
<dl class="attribute">
<dt id="django.forms.ChoiceField.choices">
<!--[django.forms.ChoiceField.choices]--><tt class="descclassname">ChoiceField.</tt><tt class="descname">choices</tt><a class="headerlink" href="#django.forms.ChoiceField.choices" title="Permalink to this definition">¶</a></dt>
<dd>An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
field.</dd></dl>

</div>
<div class="section" id="s-typedchoicefield">
<span id="typedchoicefield"></span><h3><tt class="docutils literal"><span class="pre">TypedChoiceField</span></tt><a class="headerlink" href="#typedchoicefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.TypedChoiceField">
<!--[django.forms.TypedChoiceField]-->class <tt class="descname">TypedChoiceField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.TypedChoiceField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Just like a <a title="django.forms.ChoiceField" class="reference internal" href="#django.forms.ChoiceField"><tt class="xref docutils literal"><span class="pre">ChoiceField</span></tt></a>, except <a title="django.forms.TypedChoiceField" class="reference internal" href="#django.forms.TypedChoiceField"><tt class="xref docutils literal"><span class="pre">TypedChoiceField</span></tt></a> takes an
extra <tt class="docutils literal"><span class="pre">coerce</span></tt> argument.</p>
<ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">Select</span></tt></li>
<li>Empty value: Whatever you've given as <tt class="docutils literal"><span class="pre">empty_value</span></tt></li>
<li>Normalizes to: the value returned by the <tt class="docutils literal"><span class="pre">coerce</span></tt> argument.</li>
<li>Validates that the given value exists in the list of choices.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid_choice</span></tt></li>
</ul>
<p>Takes extra arguments:</p>
<dl class="attribute">
<dt id="django.forms.TypedChoiceField.coerce">
<!--[django.forms.TypedChoiceField.coerce]--><tt class="descclassname">TypedChoiceField.</tt><tt class="descname">coerce</tt><a class="headerlink" href="#django.forms.TypedChoiceField.coerce" title="Permalink to this definition">¶</a></dt>
<dd>A function that takes one argument and returns a coerced value. Examples
include the built-in <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">bool</span></tt> and other types. Defaults
to an identity function.</dd></dl>

<dl class="attribute">
<dt id="django.forms.TypedChoiceField.empty_value">
<!--[django.forms.TypedChoiceField.empty_value]--><tt class="descclassname">TypedChoiceField.</tt><tt class="descname">empty_value</tt><a class="headerlink" href="#django.forms.TypedChoiceField.empty_value" title="Permalink to this definition">¶</a></dt>
<dd>The value to use to represent "empty." Defaults to the empty string;
<tt class="xref docutils literal"><span class="pre">None</span></tt> is another common choice here.</dd></dl>

</div>
<div class="section" id="s-datefield">
<span id="datefield"></span><h3><tt class="docutils literal"><span class="pre">DateField</span></tt><a class="headerlink" href="#datefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.DateField">
<!--[django.forms.DateField]-->class <tt class="descname">DateField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.DateField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python <tt class="docutils literal"><span class="pre">datetime.date</span></tt> object.</li>
<li>Validates that the given value is either a <tt class="docutils literal"><span class="pre">datetime.date</span></tt>,
<tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> or string formatted in a particular date format.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateField.input_formats">
<!--[django.forms.DateField.input_formats]--><tt class="descclassname">DateField.</tt><tt class="descname">input_formats</tt><a class="headerlink" href="#django.forms.DateField.input_formats" title="Permalink to this definition">¶</a></dt>
<dd>A list of formats used to attempt to convert a string to a valid
<tt class="docutils literal"><span class="pre">datetime.date</span></tt> object.</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">input_formats</span></tt> argument is provided, the default input formats are:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="s">'%Y-%m-</span><span class="si">%d</span><span class="s">'</span><span class="p">,</span> <span class="s">'%m/</span><span class="si">%d</span><span class="s">/%Y'</span><span class="p">,</span> <span class="s">'%m/</span><span class="si">%d</span><span class="s">/%y'</span><span class="p">,</span> <span class="c"># '2006-10-25', '10/25/2006', '10/25/06'</span>
<span class="s">'%b </span><span class="si">%d</span><span class="s"> %Y'</span><span class="p">,</span> <span class="s">'%b </span><span class="si">%d</span><span class="s">, %Y'</span><span class="p">,</span>            <span class="c"># 'Oct 25 2006', 'Oct 25, 2006'</span>
<span class="s">'</span><span class="si">%d</span><span class="s"> %b %Y'</span><span class="p">,</span> <span class="s">'</span><span class="si">%d</span><span class="s"> %b, %Y'</span><span class="p">,</span>            <span class="c"># '25 Oct 2006', '25 Oct, 2006'</span>
<span class="s">'%B </span><span class="si">%d</span><span class="s"> %Y'</span><span class="p">,</span> <span class="s">'%B </span><span class="si">%d</span><span class="s">, %Y'</span><span class="p">,</span>            <span class="c"># 'October 25 2006', 'October 25, 2006'</span>
<span class="s">'</span><span class="si">%d</span><span class="s"> %B %Y'</span><span class="p">,</span> <span class="s">'</span><span class="si">%d</span><span class="s"> %B, %Y'</span><span class="p">,</span>            <span class="c"># '25 October 2006', '25 October, 2006'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-datetimefield">
<span id="datetimefield"></span><h3><tt class="docutils literal"><span class="pre">DateTimeField</span></tt><a class="headerlink" href="#datetimefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.DateTimeField">
<!--[django.forms.DateTimeField]-->class <tt class="descname">DateTimeField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.DateTimeField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">DateTimeInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python <tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> object.</li>
<li>Validates that the given value is either a <tt class="docutils literal"><span class="pre">datetime.datetime</span></tt>,
<tt class="docutils literal"><span class="pre">datetime.date</span></tt> or string formatted in a particular datetime format.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateTimeField.input_formats">
<!--[django.forms.DateTimeField.input_formats]--><tt class="descclassname">DateTimeField.</tt><tt class="descname">input_formats</tt><a class="headerlink" href="#django.forms.DateTimeField.input_formats" title="Permalink to this definition">¶</a></dt>
<dd>A list of formats used to attempt to convert a string to a valid
<tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> object.</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">input_formats</span></tt> argument is provided, the default input formats are:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="s">'%Y-%m-</span><span class="si">%d</span><span class="s"> %H:%M:%S'</span><span class="p">,</span>     <span class="c"># '2006-10-25 14:30:59'</span>
<span class="s">'%Y-%m-</span><span class="si">%d</span><span class="s"> %H:%M'</span><span class="p">,</span>        <span class="c"># '2006-10-25 14:30'</span>
<span class="s">'%Y-%m-</span><span class="si">%d</span><span class="s">'</span><span class="p">,</span>              <span class="c"># '2006-10-25'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%Y %H:%M:%S'</span><span class="p">,</span>     <span class="c"># '10/25/2006 14:30:59'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%Y %H:%M'</span><span class="p">,</span>        <span class="c"># '10/25/2006 14:30'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%Y'</span><span class="p">,</span>              <span class="c"># '10/25/2006'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%y %H:%M:%S'</span><span class="p">,</span>     <span class="c"># '10/25/06 14:30:59'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%y %H:%M'</span><span class="p">,</span>        <span class="c"># '10/25/06 14:30'</span>
<span class="s">'%m/</span><span class="si">%d</span><span class="s">/%y'</span><span class="p">,</span>              <span class="c"># '10/25/06'</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.0:</span> The <tt class="docutils literal"><span class="pre">DateTimeField</span></tt> used to use a <tt class="docutils literal"><span class="pre">TextInput</span></tt> widget by default. This has now changed.</div>
</div>
<div class="section" id="s-decimalfield">
<span id="decimalfield"></span><h3><tt class="docutils literal"><span class="pre">DecimalField</span></tt><a class="headerlink" href="#decimalfield" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<dl class="class">
<dt id="django.forms.DecimalField">
<!--[django.forms.DecimalField]-->class <tt class="descname">DecimalField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.DecimalField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python <tt class="docutils literal"><span class="pre">decimal</span></tt>.</li>
<li>Validates that the given value is a decimal. Leading and trailing
whitespace is ignored.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">max_value</span></tt>,
<tt class="docutils literal"><span class="pre">min_value</span></tt>, <tt class="docutils literal"><span class="pre">max_digits</span></tt>, <tt class="docutils literal"><span class="pre">max_decimal_places</span></tt>,
<tt class="docutils literal"><span class="pre">max_whole_digits</span></tt></li>
</ul>
</dd></dl>

<p>Takes four optional arguments:</p>
<dl class="attribute">
<dt id="django.forms.DecimalField.max_value">
<!--[django.forms.DecimalField.max_value]--><tt class="descclassname">DecimalField.</tt><tt class="descname">max_value</tt><a class="headerlink" href="#django.forms.DecimalField.max_value" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.forms.DecimalField.min_value">
<!--[django.forms.DecimalField.min_value]--><tt class="descclassname">DecimalField.</tt><tt class="descname">min_value</tt><a class="headerlink" href="#django.forms.DecimalField.min_value" title="Permalink to this definition">¶</a></dt>
<dd>These attributes define the limits for the fields value.</dd></dl>

<dl class="attribute">
<dt id="django.forms.DecimalField.max_digits">
<!--[django.forms.DecimalField.max_digits]--><tt class="descclassname">DecimalField.</tt><tt class="descname">max_digits</tt><a class="headerlink" href="#django.forms.DecimalField.max_digits" title="Permalink to this definition">¶</a></dt>
<dd>The maximum number of digits (those before the decimal point plus those
after the decimal point, with leading zeros stripped) permitted in the
value.</dd></dl>

<dl class="attribute">
<dt id="django.forms.DecimalField.decimal_places">
<!--[django.forms.DecimalField.decimal_places]--><tt class="descclassname">DecimalField.</tt><tt class="descname">decimal_places</tt><a class="headerlink" href="#django.forms.DecimalField.decimal_places" title="Permalink to this definition">¶</a></dt>
<dd>The maximum number of decimal places permitted.</dd></dl>

</div>
<div class="section" id="s-emailfield">
<span id="emailfield"></span><h3><tt class="docutils literal"><span class="pre">EmailField</span></tt><a class="headerlink" href="#emailfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.EmailField">
<!--[django.forms.EmailField]-->class <tt class="descname">EmailField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.EmailField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates that the given value is a valid e-mail address, using a
moderately complex regular expression.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

<p>Has two optional arguments for validation, <tt class="docutils literal"><span class="pre">max_length</span></tt> and <tt class="docutils literal"><span class="pre">min_length</span></tt>.
If provided, these arguments ensure that the string is at most or at least the
given length.</p>
</div>
<div class="section" id="s-filefield">
<span id="filefield"></span><h3><tt class="docutils literal"><span class="pre">FileField</span></tt><a class="headerlink" href="#filefield" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<dl class="class">
<dt id="django.forms.FileField">
<!--[django.forms.FileField]-->class <tt class="descname">FileField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.FileField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">FileInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: An <tt class="docutils literal"><span class="pre">UploadedFile</span></tt> object that wraps the file content
and file name into a single object.</li>
<li>Validates that non-empty file data has been bound to the form.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">missing</span></tt>, <tt class="docutils literal"><span class="pre">empty</span></tt></li>
</ul>
</dd></dl>

<p>To learn more about the <tt class="docutils literal"><span class="pre">UploadedFile</span></tt> object, see the <a class="reference external" href="http://docs.djangoproject.com/en/1.0/topics/http/file-uploads/#topics-file-uploads"><em>file uploads
documentation</em></a>.</p>
<p>When you use a <tt class="docutils literal"><span class="pre">FileField</span></tt> in a form, you must also remember to
<a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/forms/api/#binding-uploaded-files"><em>bind the file data to the form</em></a>.</p>
</div>
<div class="section" id="s-filepathfield">
<span id="filepathfield"></span><h3><tt class="docutils literal"><span class="pre">FilePathField</span></tt><a class="headerlink" href="#filepathfield" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<dl class="class">
<dt id="django.forms.FilePathField">
<!--[django.forms.FilePathField]-->class <tt class="descname">FilePathField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.FilePathField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">Select</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A unicode object</li>
<li>Validates that the selected choice exists in the list of choices.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid_choice</span></tt></li>
</ul>
</dd></dl>

<p>The field allows choosing from files inside a certain directory. It takes three
extra arguments; only <tt class="docutils literal"><span class="pre">path</span></tt> is required:</p>
<dl class="attribute">
<dt id="django.forms.FilePathField.path">
<!--[django.forms.FilePathField.path]--><tt class="descclassname">FilePathField.</tt><tt class="descname">path</tt><a class="headerlink" href="#django.forms.FilePathField.path" title="Permalink to this definition">¶</a></dt>
<dd>The absolute path to the directory whose contents you want listed. This
directory must exist.</dd></dl>

<dl class="attribute">
<dt id="django.forms.FilePathField.recursive">
<!--[django.forms.FilePathField.recursive]--><tt class="descclassname">FilePathField.</tt><tt class="descname">recursive</tt><a class="headerlink" href="#django.forms.FilePathField.recursive" title="Permalink to this definition">¶</a></dt>
<dd>If <tt class="xref docutils literal"><span class="pre">False</span></tt> (the default) only the direct contents of <tt class="docutils literal"><span class="pre">path</span></tt> will be
offered as choices. If <tt class="xref docutils literal"><span class="pre">True</span></tt>, the directory will be descended into
recursively and all descendants will be listed as choices.</dd></dl>

<dl class="attribute">
<dt id="django.forms.FilePathField.match">
<!--[django.forms.FilePathField.match]--><tt class="descclassname">FilePathField.</tt><tt class="descname">match</tt><a class="headerlink" href="#django.forms.FilePathField.match" title="Permalink to this definition">¶</a></dt>
<dd>A regular expression pattern; only files with names matching this expression
will be allowed as choices.</dd></dl>

</div>
<div class="section" id="s-floatfield">
<span id="floatfield"></span><h3><tt class="docutils literal"><span class="pre">FloatField</span></tt><a class="headerlink" href="#floatfield" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python float.</li>
<li>Validates that the given value is an float. Leading and trailing
whitespace is allowed, as in Python's <tt class="docutils literal"><span class="pre">float()</span></tt> function.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">max_value</span></tt>,
<tt class="docutils literal"><span class="pre">min_value</span></tt></li>
</ul>
<p>Takes two optional arguments for validation, <tt class="docutils literal"><span class="pre">max_value</span></tt> and <tt class="docutils literal"><span class="pre">min_value</span></tt>.
These control the range of values permitted in the field.</p>
</div>
<div class="section" id="s-imagefield">
<span id="imagefield"></span><h3><tt class="docutils literal"><span class="pre">ImageField</span></tt><a class="headerlink" href="#imagefield" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<dl class="class">
<dt id="django.forms.ImageField">
<!--[django.forms.ImageField]-->class <tt class="descname">ImageField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.ImageField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">FileInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: An <tt class="docutils literal"><span class="pre">UploadedFile</span></tt> object that wraps the file content
and file name into a single object.</li>
<li>Validates that file data has been bound to the form, and that the
file is of an image format understood by PIL.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">missing</span></tt>, <tt class="docutils literal"><span class="pre">empty</span></tt>,
<tt class="docutils literal"><span class="pre">invalid_image</span></tt></li>
</ul>
</dd></dl>

<p>Using an ImageField requires that the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> is installed.</p>
<p>When you use an <tt class="docutils literal"><span class="pre">ImageField</span></tt> on a form, you must also remember to
<a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/forms/api/#binding-uploaded-files"><em>bind the file data to the form</em></a>.</p>
</div>
<div class="section" id="s-integerfield">
<span id="integerfield"></span><h3><tt class="docutils literal"><span class="pre">IntegerField</span></tt><a class="headerlink" href="#integerfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.IntegerField">
<!--[django.forms.IntegerField]-->class <tt class="descname">IntegerField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.IntegerField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python integer or long integer.</li>
<li>Validates that the given value is an integer. Leading and trailing
whitespace is allowed, as in Python's <tt class="docutils literal"><span class="pre">int()</span></tt> function.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">max_value</span></tt>,
<tt class="docutils literal"><span class="pre">min_value</span></tt></li>
</ul>
</dd></dl>

<p>Takes two optional arguments for validation:</p>
<dl class="attribute">
<dt id="django.forms.IntegerField.max_value">
<!--[django.forms.IntegerField.max_value]--><tt class="descclassname">IntegerField.</tt><tt class="descname">max_value</tt><a class="headerlink" href="#django.forms.IntegerField.max_value" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.forms.IntegerField.min_value">
<!--[django.forms.IntegerField.min_value]--><tt class="descclassname">IntegerField.</tt><tt class="descname">min_value</tt><a class="headerlink" href="#django.forms.IntegerField.min_value" title="Permalink to this definition">¶</a></dt>
<dd>These control the range of values permitted in the field.</dd></dl>

</div>
<div class="section" id="s-ipaddressfield">
<span id="ipaddressfield"></span><h3><tt class="docutils literal"><span class="pre">IPAddressField</span></tt><a class="headerlink" href="#ipaddressfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.IPAddressField">
<!--[django.forms.IPAddressField]-->class <tt class="descname">IPAddressField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.IPAddressField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates that the given value is a valid IPv4 address, using a regular
expression.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

</div>
<div class="section" id="s-multiplechoicefield">
<span id="multiplechoicefield"></span><h3><tt class="docutils literal"><span class="pre">MultipleChoiceField</span></tt><a class="headerlink" href="#multiplechoicefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.MultipleChoiceField">
<!--[django.forms.MultipleChoiceField]-->class <tt class="descname">MultipleChoiceField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.MultipleChoiceField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">SelectMultiple</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">[]</span></tt> (an empty list)</li>
<li>Normalizes to: A list of Unicode objects.</li>
<li>Validates that every value in the given list of values exists in the list
of choices.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid_choice</span></tt>, <tt class="docutils literal"><span class="pre">invalid_list</span></tt></li>
</ul>
</dd></dl>

<p>Takes one extra argument, <tt class="docutils literal"><span class="pre">choices</span></tt>, as for <tt class="docutils literal"><span class="pre">ChoiceField</span></tt>.</p>
</div>
<div class="section" id="s-nullbooleanfield">
<span id="nullbooleanfield"></span><h3><tt class="docutils literal"><span class="pre">NullBooleanField</span></tt><a class="headerlink" href="#nullbooleanfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.NullBooleanField">
<!--[django.forms.NullBooleanField]-->class <tt class="descname">NullBooleanField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.NullBooleanField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">NullBooleanSelect</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python <tt class="xref docutils literal"><span class="pre">True</span></tt>, <tt class="xref docutils literal"><span class="pre">False</span></tt> or <tt class="xref docutils literal"><span class="pre">None</span></tt> value.</li>
<li>Validates nothing (i.e., it never raises a <tt class="docutils literal"><span class="pre">ValidationError</span></tt>).</li>
</ul>
</dd></dl>

</div>
<div class="section" id="s-regexfield">
<span id="regexfield"></span><h3><tt class="docutils literal"><span class="pre">RegexField</span></tt><a class="headerlink" href="#regexfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.RegexField">
<!--[django.forms.RegexField]-->class <tt class="descname">RegexField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.RegexField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates that the given value matches against a certain regular
expression.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

<p>Takes one required argument:</p>
<dl class="attribute">
<dt id="django.forms.RegexField.regex">
<!--[django.forms.RegexField.regex]--><tt class="descclassname">RegexField.</tt><tt class="descname">regex</tt><a class="headerlink" href="#django.forms.RegexField.regex" title="Permalink to this definition">¶</a></dt>
<dd>A regular expression specified either as a string or a compiled regular
expression object.</dd></dl>

<p>Also takes <tt class="docutils literal"><span class="pre">max_length</span></tt> and <tt class="docutils literal"><span class="pre">min_length</span></tt>, which work just as they do for
<tt class="docutils literal"><span class="pre">CharField</span></tt>.</p>
<p>The optional argument <tt class="docutils literal"><span class="pre">error_message</span></tt> is also accepted for backwards
compatibility. The preferred way to provide an error message is to use the
<tt class="docutils literal"><span class="pre">error_messages</span></tt> argument, passing a dictionary with <tt class="docutils literal"><span class="pre">'invalid'</span></tt> as a key
and the error message as the value.</p>
</div>
<div class="section" id="s-timefield">
<span id="timefield"></span><h3><tt class="docutils literal"><span class="pre">TimeField</span></tt><a class="headerlink" href="#timefield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.TimeField">
<!--[django.forms.TimeField]-->class <tt class="descname">TimeField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.TimeField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="xref docutils literal"><span class="pre">None</span></tt></li>
<li>Normalizes to: A Python <tt class="docutils literal"><span class="pre">datetime.time</span></tt> object.</li>
<li>Validates that the given value is either a <tt class="docutils literal"><span class="pre">datetime.time</span></tt> or string
formatted in a particular time format.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt></li>
</ul>
</dd></dl>

<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.TimeField.input_formats">
<!--[django.forms.TimeField.input_formats]--><tt class="descclassname">TimeField.</tt><tt class="descname">input_formats</tt><a class="headerlink" href="#django.forms.TimeField.input_formats" title="Permalink to this definition">¶</a></dt>
<dd>A list of formats used to attempt to convert a string to a valid
<tt class="docutils literal"><span class="pre">datetime.time</span></tt> object.</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">input_formats</span></tt> argument is provided, the default input formats are:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="s">'%H:%M:%S'</span><span class="p">,</span>     <span class="c"># '14:30:59'</span>
<span class="s">'%H:%M'</span><span class="p">,</span>        <span class="c"># '14:30'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-urlfield">
<span id="urlfield"></span><h3><tt class="docutils literal"><span class="pre">URLField</span></tt><a class="headerlink" href="#urlfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.URLField">
<!--[django.forms.URLField]-->class <tt class="descname">URLField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.URLField" title="Permalink to this definition">¶</a></dt>
<dd><ul class="simple">
<li>Default widget: <tt class="docutils literal"><span class="pre">TextInput</span></tt></li>
<li>Empty value: <tt class="docutils literal"><span class="pre">''</span></tt> (an empty string)</li>
<li>Normalizes to: A Unicode object.</li>
<li>Validates that the given value is a valid URL.</li>
<li>Error message keys: <tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">invalid_link</span></tt></li>
</ul>
</dd></dl>

<p>Takes the following optional arguments:</p>
<dl class="attribute">
<dt id="django.forms.URLField.max_length">
<!--[django.forms.URLField.max_length]--><tt class="descclassname">URLField.</tt><tt class="descname">max_length</tt><a class="headerlink" href="#django.forms.URLField.max_length" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.forms.URLField.min_length">
<!--[django.forms.URLField.min_length]--><tt class="descclassname">URLField.</tt><tt class="descname">min_length</tt><a class="headerlink" href="#django.forms.URLField.min_length" title="Permalink to this definition">¶</a></dt>
<dd>Same as <tt class="docutils literal"><span class="pre">CharField.max_length</span></tt> and <tt class="docutils literal"><span class="pre">CharField.min_length</span></tt>.</dd></dl>

<dl class="attribute">
<dt id="django.forms.URLField.verify_exists">
<!--[django.forms.URLField.verify_exists]--><tt class="descclassname">URLField.</tt><tt class="descname">verify_exists</tt><a class="headerlink" href="#django.forms.URLField.verify_exists" title="Permalink to this definition">¶</a></dt>
<dd>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, the validator will attempt to load the given URL, raising
<tt class="docutils literal"><span class="pre">ValidationError</span></tt> if the page gives a 404. Defaults to <tt class="xref docutils literal"><span class="pre">False</span></tt>.</dd></dl>

<dl class="attribute">
<dt id="django.forms.URLField.validator_user_agent">
<!--[django.forms.URLField.validator_user_agent]--><tt class="descclassname">URLField.</tt><tt class="descname">validator_user_agent</tt><a class="headerlink" href="#django.forms.URLField.validator_user_agent" title="Permalink to this definition">¶</a></dt>
<dd>String used as the user-agent used when checking for a URL's existence.
Defaults to the value of the <tt class="docutils literal"><span class="pre">URL_VALIDATOR_USER_AGENT</span></tt> setting.</dd></dl>

</div>
</div>
<div class="section" id="s-slightly-complex-built-in-field-classes">
<span id="slightly-complex-built-in-field-classes"></span><h2>Slightly complex built-in <tt class="docutils literal"><span class="pre">Field</span></tt> classes<a class="headerlink" href="#slightly-complex-built-in-field-classes" title="Permalink to this headline">¶</a></h2>
<p>The following are not yet documented.</p>
<dl class="class">
<dt id="django.forms.ComboField">
<!--[django.forms.ComboField]-->class <tt class="descname">ComboField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.ComboField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="class">
<dt id="django.forms.MultiValueField">
<!--[django.forms.MultiValueField]-->class <tt class="descname">MultiValueField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.MultiValueField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="class">
<dt id="django.forms.SplitDateTimeField">
<!--[django.forms.SplitDateTimeField]-->class <tt class="descname">SplitDateTimeField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.SplitDateTimeField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-fields-which-handle-relationships">
<span id="fields-which-handle-relationships"></span><h2>Fields which handle relationships<a class="headerlink" href="#fields-which-handle-relationships" title="Permalink to this headline">¶</a></h2>
<p>For representing relationships between models, two fields are
provided which can derive their choices from a <tt class="docutils literal"><span class="pre">QuerySet</span></tt>:</p>
<dl class="class">
<dt id="django.forms.ModelChoiceField">
<!--[django.forms.ModelChoiceField]-->class <tt class="descname">ModelChoiceField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.ModelChoiceField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="class">
<dt id="django.forms.ModelMultipleChoiceField">
<!--[django.forms.ModelMultipleChoiceField]-->class <tt class="descname">ModelMultipleChoiceField</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.forms.ModelMultipleChoiceField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>These fields place one or more model objects into the <tt class="docutils literal"><span class="pre">cleaned_data</span></tt>
dictionary of forms in which they're used. Both of these fields have an
additional required argument:</p>
<dl class="attribute">
<dt id="django.forms.ModelChoiceField.queryset">
<!--[django.forms.ModelChoiceField.queryset]--><tt class="descclassname">ModelChoiceField.</tt><tt class="descname">queryset</tt><a class="headerlink" href="#django.forms.ModelChoiceField.queryset" title="Permalink to this definition">¶</a></dt>
<dd>A <tt class="docutils literal"><span class="pre">QuerySet</span></tt> of model objects from which the choices for the
field will be derived, and which will be used to validate the
user's selection.</dd></dl>

<div class="section" id="s-modelchoicefield">
<span id="modelchoicefield"></span><h3><tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt><a class="headerlink" href="#modelchoicefield" title="Permalink to this headline">¶</a></h3>
<p>Allows the selection of a single model object, suitable for
representing a foreign key.</p>
<p>The <tt class="docutils literal"><span class="pre">__unicode__</span></tt> method of the model will be called to generate
string representations of the objects for use in the field's choices;
to provide customized representations, subclass <tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt>
and override <tt class="docutils literal"><span class="pre">label_from_instance</span></tt>. This method will receive a model
object, and should return a string suitable for representing it. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyModelChoiceField</span><span class="p">(</span><span class="n">ModelChoiceField</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">label_from_instance</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">"My Object #</span><span class="si">%i</span><span class="s">"</span> <span class="o">%</span> <span class="n">obj</span><span class="o">.</span><span class="n">id</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="django.forms.ModelChoiceField.empty_label">
<!--[django.forms.ModelChoiceField.empty_label]--><tt class="descclassname">ModelChoiceField.</tt><tt class="descname">empty_label</tt><a class="headerlink" href="#django.forms.ModelChoiceField.empty_label" title="Permalink to this definition">¶</a></dt>
<dd><p>By default the <tt class="docutils literal"><span class="pre">&lt;select&gt;</span></tt> widget used by <tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt> will have a
an empty choice at the top of the list. You can change the text of this label
(which is <tt class="docutils literal"><span class="pre">"---------"</span></tt> by default) with the <tt class="docutils literal"><span class="pre">empty_label</span></tt> attribute, or
you can disable the empty label entirely by setting <tt class="docutils literal"><span class="pre">empty_label</span></tt> to
<tt class="xref docutils literal"><span class="pre">None</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># A custom empty label</span>
<span class="n">field1</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">ModelChoiceField</span><span class="p">(</span><span class="n">queryset</span><span class="o">=...</span><span class="p">,</span> <span class="n">empty_label</span><span class="o">=</span><span class="s">"(Nothing)"</span><span class="p">)</span>

<span class="c"># No empty label</span>
<span class="n">field2</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">ModelChoiceField</span><span class="p">(</span><span class="n">queryset</span><span class="o">=...</span><span class="p">,</span> <span class="n">empty_label</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that if a <tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt> is required and has a default
initial value, no empty choice is created (regardless of the value
of <tt class="docutils literal"><span class="pre">empty_label</span></tt>).</p>
</dd></dl>

</div>
<div class="section" id="s-modelmultiplechoicefield">
<span id="modelmultiplechoicefield"></span><h3><tt class="docutils literal"><span class="pre">ModelMultipleChoiceField</span></tt><a class="headerlink" href="#modelmultiplechoicefield" title="Permalink to this headline">¶</a></h3>
<p>Allows the selection of one or more model objects, suitable for
representing a many-to-many relation. As with <tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt>,
you can use <tt class="docutils literal"><span class="pre">label_from_instance</span></tt> to customize the object
representations.</p>
</div>
</div>
<div class="section" id="s-creating-custom-fields">
<span id="creating-custom-fields"></span><h2>Creating custom fields<a class="headerlink" href="#creating-custom-fields" title="Permalink to this headline">¶</a></h2>
<p>If the built-in <tt class="docutils literal"><span class="pre">Field</span></tt> classes don't meet your needs, you can easily create
custom <tt class="docutils literal"><span class="pre">Field</span></tt> classes. To do this, just create a subclass of
<tt class="docutils literal"><span class="pre">django.forms.Field</span></tt>. Its only requirements are that it implement a
<tt class="docutils literal"><span class="pre">clean()</span></tt> method and that its <tt class="docutils literal"><span class="pre">__init__()</span></tt> method accept the core arguments
mentioned above (<tt class="docutils literal"><span class="pre">required</span></tt>, <tt class="docutils literal"><span class="pre">label</span></tt>, <tt class="docutils literal"><span class="pre">initial</span></tt>, <tt class="docutils literal"><span class="pre">widget</span></tt>,
<tt class="docutils literal"><span class="pre">help_text</span></tt>).</p>
</div>
</div>



<div id="content-secondary">
  <h2 id="comments">Questions/Feedback</h2>
  <p>Having trouble? We'd like to help!</p>
  <ul>
    <li>
      Try the <a href="http://docs.djangoproject.com/en/dev/faq/">FAQ</a> — it's got answers to many common
      questions.
    </li>
    <li>
      Search for information in the <a href="http://groups.google.com/group/django-users/">archives of the
      django-users mailing list</a>, or <a href="http://groups.google.com/group/django-users/">post a question</a>.
    </li>
    <li>
      Ask a question in the <a href="irc://irc.freenode.net/">#django IRC
      channel</a>, or search the <a href="http://oebfare.com/logger/django/">IRC
      logs</a> to see if its been asked before.
    </li>
    <li>
      If you notice errors with this documentation, please <a href="http://code.djangoproject.com/simpleticket?component=Documentation">
      open a ticket</a> and let us know! Please only use the ticket tracker for
      criticisms and improvements on the docs. For tech support, use the
      resources above.
    </li>
  </ul>
</div>

		</div>
		<!-- END #content-main -->
		<div id="content-related" class="sidebar">
		
  
    <h2>Contents</h2>
    
      <ul>
<li><a class="reference external" href="">Form fields</a><ul>
<li><a class="reference external" href="#core-field-arguments">Core field arguments</a><ul>
<li><a class="reference external" href="#required"><tt class="docutils literal"><span class="pre">required</span></tt></a></li>
<li><a class="reference external" href="#label"><tt class="docutils literal"><span class="pre">label</span></tt></a></li>
<li><a class="reference external" href="#initial"><tt class="docutils literal"><span class="pre">initial</span></tt></a></li>
<li><a class="reference external" href="#widget"><tt class="docutils literal"><span class="pre">widget</span></tt></a></li>
<li><a class="reference external" href="#help-text"><tt class="docutils literal"><span class="pre">help_text</span></tt></a></li>
<li><a class="reference external" href="#error-messages"><tt class="docutils literal"><span class="pre">error_messages</span></tt></a></li>
</ul>
</li>
<li><a class="reference external" href="#built-in-field-classes">Built-in <tt class="docutils literal"><span class="pre">Field</span></tt> classes</a><ul>
<li><a class="reference external" href="#booleanfield"><tt class="docutils literal"><span class="pre">BooleanField</span></tt></a></li>
<li><a class="reference external" href="#charfield"><tt class="docutils literal"><span class="pre">CharField</span></tt></a></li>
<li><a class="reference external" href="#choicefield"><tt class="docutils literal"><span class="pre">ChoiceField</span></tt></a></li>
<li><a class="reference external" href="#typedchoicefield"><tt class="docutils literal"><span class="pre">TypedChoiceField</span></tt></a></li>
<li><a class="reference external" href="#datefield"><tt class="docutils literal"><span class="pre">DateField</span></tt></a></li>
<li><a class="reference external" href="#datetimefield"><tt class="docutils literal"><span class="pre">DateTimeField</span></tt></a></li>
<li><a class="reference external" href="#decimalfield"><tt class="docutils literal"><span class="pre">DecimalField</span></tt></a></li>
<li><a class="reference external" href="#emailfield"><tt class="docutils literal"><span class="pre">EmailField</span></tt></a></li>
<li><a class="reference external" href="#filefield"><tt class="docutils literal"><span class="pre">FileField</span></tt></a></li>
<li><a class="reference external" href="#filepathfield"><tt class="docutils literal"><span class="pre">FilePathField</span></tt></a></li>
<li><a class="reference external" href="#floatfield"><tt class="docutils literal"><span class="pre">FloatField</span></tt></a></li>
<li><a class="reference external" href="#imagefield"><tt class="docutils literal"><span class="pre">ImageField</span></tt></a></li>
<li><a class="reference external" href="#integerfield"><tt class="docutils literal"><span class="pre">IntegerField</span></tt></a></li>
<li><a class="reference external" href="#ipaddressfield"><tt class="docutils literal"><span class="pre">IPAddressField</span></tt></a></li>
<li><a class="reference external" href="#multiplechoicefield"><tt class="docutils literal"><span class="pre">MultipleChoiceField</span></tt></a></li>
<li><a class="reference external" href="#nullbooleanfield"><tt class="docutils literal"><span class="pre">NullBooleanField</span></tt></a></li>
<li><a class="reference external" href="#regexfield"><tt class="docutils literal"><span class="pre">RegexField</span></tt></a></li>
<li><a class="reference external" href="#timefield"><tt class="docutils literal"><span class="pre">TimeField</span></tt></a></li>
<li><a class="reference external" href="#urlfield"><tt class="docutils literal"><span class="pre">URLField</span></tt></a></li>
</ul>
</li>
<li><a class="reference external" href="#slightly-complex-built-in-field-classes">Slightly complex built-in <tt class="docutils literal"><span class="pre">Field</span></tt> classes</a></li>
<li><a class="reference external" href="#fields-which-handle-relationships">Fields which handle relationships</a><ul>
<li><a class="reference external" href="#modelchoicefield"><tt class="docutils literal"><span class="pre">ModelChoiceField</span></tt></a></li>
<li><a class="reference external" href="#modelmultiplechoicefield"><tt class="docutils literal"><span class="pre">ModelMultipleChoiceField</span></tt></a></li>
</ul>
</li>
<li><a class="reference external" href="#creating-custom-fields">Creating custom fields</a></li>
</ul>
</li>
</ul>

    
  
  
  
    <h2>Search</h2>
    
    <form action="/en/1.0/search/" id="search" class="search">
  <div>
    <input name="cx" value="009763561546736975936:e88ek0eurf4" type="hidden">
    <input name="cof" value="FORID:11" type="hidden">
    <input name="ie" value="UTF-8" type="hidden">
    <input name="hl" value="" type="hidden">
    <input style="background: rgb(255, 255, 255) url(http://www.google.com/coop/intl/en/images/google_custom_search_watermark.gif) no-repeat scroll left center; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" id="id_search_q" class="query" name="q" type="text">
    <input name="sa" class="submit" value="Search" type="submit">
    <ul>
<li><label for="id_search_as_q_0"><input checked="checked" id="id_search_as_q_0" value="more:dev_docs" name="as_q" type="radio"> Latest</label></li>
<li><label for="id_search_as_q_1"><input id="id_search_as_q_1" value="more:1.0_docs" name="as_q" type="radio"> 1.0</label></li>
<li><label for="id_search_as_q_2"><input id="id_search_as_q_2" value="more:0.96_docs" name="as_q" type="radio"> 0.96</label></li>
<li><label for="id_search_as_q_3"><input id="id_search_as_q_3" value="more:all_docs" name="as_q" type="radio"> All</label></li>
</ul>
  </div>
</form>
<script type="text/javascript" src="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/brand.html"></script>
  
  
  
    <h2>Browse</h2>
    <ul>
      
        
          <li>Prev: <a href="http://docs.djangoproject.com/en/1.0/ref/forms/api/">The Forms API</a></li>
        
        
          <li>Next: <a href="http://docs.djangoproject.com/en/1.0/ref/forms/widgets/">Widgets</a></li>
        
        <li><a href="http://docs.djangoproject.com/en/1.0/contents/">Table of contents</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/genindex/">General Index</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/modindex/">Global Module Index</a></li>
        
      
    </ul>
  
  
  
    <h2>You are here:</h2>
    <ul>
      
        <li>
          <a href="http://docs.djangoproject.com/en/1.0/">Django 1.0 documentation</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/">API Reference</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/forms/">Forms</a>
          
          <ul><li>Form fields</li></ul>
          </li></ul></li></ul>
        </li>
      
    </ul>
  
  
  
    <h3>Last update:</h3>
    <div>May 23, 2009, 8:15 a.m. (<a href="http://www.timeanddate.com/worldclock/city.html?n=64">CDT</a>)</div>
  

		</div>
		<!-- END #content-related -->

		</div>
		<!-- END #content -->
		<div id="footer">
			<p>© 2005-2009 <a href="http://www.djangoproject.com/foundation/">Django Software Foundation</a> unless otherwise noted. Django is a registered trademark of the Django Software Foundation. 
			Hosting graciously provided by <a href="http://mediatemple.net/">
			<img style="vertical-align: middle; position: relative; top: -1px;" src="Django%20%7C%20Form%20fields%20%7C%20Django%20Documentation_files/mt.png" alt="media temple"></a>
			</p>
		</div>
		<!-- END #footer -->
	</div>
	<!-- END #container -->
	</body></html>